feat: render and time a real basemap in the browser gate, and emit MapLibre's worker (#63) - #314

What this is

Refs #63. Deliberately not a closing keyword — criterion 8 is only partly discharged and criterion 1's second half depends on a hosted archive that does not exist. CLAUDE.md §7 is explicit that the keyword has to be right when the PR is opened, and both prior comments on #63 left it open for exactly this reason (ADR 0010's open question 3 names #63 as the owner of the cold-load measurement, and an ADR body is never edited in place). Refs #53 as well, which owns the other half.

#63 has had seven of eight criteria since #175/#176. The eighth — "Cold-load behaviour is measured and recorded in the PR: time to first painted tile on a cold cache" — could not be taken, because there was no archive, so no tile was ever painted and there was nothing to time. map.browser.spec.ts said so, and predicted the fix: "the day #53 lands, that test goes red — which is the right moment for somebody to come back and replace it with one that asserts tiles actually drew."

This is that moment arriving from the other direction. The client's share of a cold load is ours, it does not need a host, and measuring it is what will let the hosted number — when there is one — be read as latency rather than as an unexplained total.

The defect this found

A production map fetched every tile and drew none of them, silently.

MapLibre v6 parses every vector tile in a Web Worker and locates it with new URL('./maplibre-gl-worker.mjs', import.meta.url). Under a bundler import.meta.url is the hashed chunk MapLibre was bundled into, and the expression is built from a variable, so it is not statically analysable and no bundler emits the file. The script 404s, the Worker object is constructed anyway, every loadTile message is sent into it and never answered, and the tile sits in loading for ever.

Every symptom is an absence. No exception, create returns normally, live GL context, correct origin, correct range request, registrations === 1, no map error. The existing browser gate was green through all of it — and was right to be, because there was no tile for the worker to fail to parse.

RESP 404 http://127.0.0.1:4319/assets/maplibre-gl-worker.mjs
REQFAIL     http://127.0.0.1:4319/assets/maplibre-gl-worker.mjs net::ERR_FAILED
RESP 206 http://127.0.0.1:4319/basemap-fixture.pmtiles bytes 0-519/520

The fix is one line in apps/web/src/map/maplibre.ts:

import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
setWorkerUrl(workerUrl);

⚠️ ?worker&url and not ?url. The dist worker imports its sibling maplibre-gl-shared.mjs; a verbatim copy of the one file fails on its first import and produces the same blank map by a different route. pnpm run build now emits assets/maplibre-gl-worker-*.js (486 kB), referenced only from the lazy map chunk — the code split is unchanged and the entry chunk still names nothing but the chunk filename.

This is a known MapLibre v6 + bundler trap rather than a discovery: see organicmaps/gtfs-osm-matcher#167, f5/unovis#921 and openwatersio/openwaters.io#122. It was reached here from the symptom, then confirmed against those.

What was built

Three decisions worth a reviewer's attention:

• The archive is not committed. browser/dist is already gitignored and already pruned by check-repo-rules.sh. A binary in the tree would need an .spdx-exempt entry §3a would refuse it, and nobody can read it in review.
• It is served at /basemap-fixture.pmtiles, not /basemap.pmtiles. The "Publish and serve the PMTiles basemap and routing engine #53 has published nothing" test asserts the 404 at the latter and stays exactly as it was. Moving the fixture there would make a tripwire permanently green against a file of our own — a test that cannot fail.
• It contains no OpenStreetMap data. ODbL attribution attaches to a Produced Work derived from OSM; a fixture carrying a scrap of real coastline would quietly make a build artefact a derivative. The metadata section deliberately carries no attribution field. The product's own credit is a separate criterion and is untouched.

Criterion 8 — the measurement, and what it leaves out

From the gate's own log, printed on every run (and annotated):

cold load — first painted tile 186.7 ms after the map was created,
222.2 ms after navigation started; 3 archive range request(s) costing
3.2 ms in total; 7 frames probed; served from the loopback interface,
so this is the client-side floor and carries none of the hosting
latency #53 owns

⚠️ This does not discharge criterion 8 and is not claimed to. Its last sentence points at hosting — ADR 0010 D-1 quotes Protomaps' warning that R2 is "known to have higher latency (500 ms or higher)" — and a loopback server removes that term by construction. The tile is uncompressed and 98 bytes; a real one is gzipped and thousands of times larger. This is a headless Chromium on a software rasteriser. What it gives is the floor, a decomposition (the range requests are reported beside the total), and a harness already in place to take the hosted measurement.

⚠️ One number worth carrying into #53: three range requests, not two. The header and root directory arrive together in one 16 KB prefetch and are cached for the life of the page; tiles are not — SharedPromiseCache caches headers and directories only, so every visible tile is its own range request even when they all resolve to the same bytes. On a high-latency store that multiplier is the cold-load cost. A first draft of the comment asserted "two round trips, no more"; the run said three, and the comment now says what the run said.

⚠️ No wall-clock threshold is asserted and one must not be added. Only sanity bounds. An absolute millisecond gate on a shared runner is flaky, a flaky gate gets disabled, and a disabled gate is how a performance claim survives with nobody re-running it — the reasoning game.browser.spec.ts already records for the shading cost, followed here.

How the paint is read

preserveDrawingBuffer is off in shipping code and must stay off — it is a per-frame cost paid by every rider so a test can read a pixel. The harness forces it on for its own page by patching HTMLCanvasElement.prototype.getContext before the map is built.

⚠️ The obvious alternative was tried and does not work, recorded so nobody tries it again: wrapping window.requestAnimationFrame before the map exists, so the probe runs immediately after MapLibre's frame callback. Every sample came back #000000. MapLibre v6 reaches its renderer through browser.frameAsync, which resolves a promise from the frame callback, so the draw happens in a microtask after anything chained synchronously onto it — the probe was reading a buffer that had already been presented and cleared.

The cost of the readback is in the reported number, and is identical on the fixture page and the control page, so the two remain comparable.

Mutations — §5's gate

Each mutation was applied to a clean tree, the suite run, and the file restored byte-identically.

The fixture, against pmtiles-fixture.test.ts

The gate, against map.browser.spec.ts

Gates

Every command below was run on this branch at the pinned Node 24.20.0 / pnpm 11.18.0, against Chromium revision 1243 (the revision @playwright/test 1.63.0 pins).

Coverage

Reported, not gated — the gate is the mutation list above.

The denominator moves by one and the numerator does not: setWorkerUrl(workerUrl) is a production statement that only executes in a real browser, and the browser gate is not instrumented. apps/web/browser/** is outside the coverage report's apps/*/src/** patterns, the same way packages/fit/tools/** is (#110) and for the same reason — a fixture generator's coverage does not belong in a client's denominator.

Security

• No dependency added, removed or bumped. pnpm-lock.yaml and every package.json are untouched; check:licences re-run and green.
• Nothing shipped changed but one configuration call, whose argument is a build-time constant emitted by the bundler onto our own origin. No user input reaches it.
• The ?archive= and ?paintDeadline= switches are harness-only (apps/web/browser/), which vite.browser.config.ts keeps out of the shipping bundle by being a second config; the product reads its archive URL from VITE_BASEMAP_PMTILES_URL as before.
• Criterion 3 re-checked on a page where tiles actually flowed, rather than one whose source 404d: every request is asserted to be on the configured origin. That is a stronger execution of "intercepts all network traffic during a map render" than was previously possible.
• No location data, no cross-athlete read, no persistence path, no file parsing of user input, no trainer control. The one new parser (protobuf/PMTiles) runs only in a test and a build script, over bytes this repository generated.

Deliberately not done

• Criterion 8's hosted half. Needs Publish and serve the PMTiles basemap and routing engine #53, which needs Package the instance as a one-command self-hostable deployment #52, which is Phase 3.
• Criterion 1's "renders its trace over the basemap" against a real basemap. Proved against the fixture; a real one is Publish and serve the PMTiles basemap and routing engine #53's.
• Glyphs and sprites. basemapStyle still emits neither, so the map draws geometry without labels. ADR 0010 has no rule for them and Publish and serve the PMTiles basemap and routing engine #53 must publish them on the basemap's own origin — the finding recorded on Render activity maps with MapLibre GL JS and self-hosted PMTiles #63 and Publish and serve the PMTiles basemap and routing engine #53 previously, unchanged.
• Nothing was changed about the existing six browser tests, on purpose. They are the tripwire for Publish and serve the PMTiles basemap and routing engine #53.

🤖 Generated with Claude Code

https://claude.ai/code/session_016X4EwacF1KuXDPhXzunifS